docs: GitHub releases are the CHANGELOG section condensed, never copied - #10810
Merged
Conversation
Adopt the release rule kurrentschrift set on 2026-08-28: a release body carries an intro line (merge count, PR range, link to CHANGELOG.md), the section's own headings in the section's order, one bullet per notable entry at most two lines long (bold title, one clause with the essence or the headline number, PR reference) and a compare link as the last line. Chores, dependency bumps and small fixes stay out; numbers are copied exactly; only PR numbers from the section are cited; the full text lives only in the CHANGELOG. The v3.1.0 release page was the whole section copied — 640 lines. The rule gets its own "Changelog + releases" section in CLAUDE.md and .github/copilot-instructions.md (the PR-gate bullet moves there, the Important Rules keep a pointer), the CHANGELOG header states the cut procedure, and agentic/commands/release.md step 7 builds the condensed body instead of copying the section (and the file list corrects itself to the four files step 4 already names). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016joUzstV3siE3WqJtbcych
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016joUzstV3siE3WqJtbcych
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
The new [Unreleased] changelog entry is missing its PR reference, which conflicts with the documented and existing changelog convention that bullets include a PR number.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
Updates the project’s release documentation to formalize the rule that GitHub release bodies must be a condensed index of the corresponding CHANGELOG.md section (not a verbatim copy), and aligns the documented release procedure accordingly.
Changes:
- Adds a dedicated “Changelog + releases” section to
CLAUDE.mdand.github/copilot-instructions.md, and points the “Important Rules” list at it. - Expands the
CHANGELOG.mdheader guidance to document the condensed-release shape and adds an[Unreleased]entry describing the rule. - Updates
agentic/commands/release.mdstep 7 to describe creating condensed GitHub release notes (and fixes the “exactly three files” → “exactly four files” wording).
File summaries
| File | Description |
|---|---|
CLAUDE.md |
Moves changelog/release guidance into a dedicated “Changelog + releases” section and links to it from Important Rules. |
CHANGELOG.md |
Documents the condensed-release rule in the header and adds an [Unreleased] entry describing the change. |
agentic/commands/release.md |
Updates the release procedure to generate condensed GitHub release notes and corrects the release-PR file-count wording. |
.github/copilot-instructions.md |
Mirrors CLAUDE.md by adding the “Changelog + releases” section and linking to it from Important Rules. |
Review details
- Files reviewed: 4/4 changed files
- Comments generated: 1
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Contributor
There was a problem hiding this comment.
🟢 Approval recommended
The changes are documentation-only, internally consistent across the synchronized instruction files, and include the required CHANGELOG.md entry under [Unreleased].
Review details
- Files reviewed: 4/4 changed files
- Comments generated: 0 new
- Review effort level: Lite
MarkusNeusinger
added a commit
that referenced
this pull request
Aug 28, 2026
## Summary - **v3.2.0 — Findable by assistants.** `[Unreleased]` moves under `## [3.2.0] — 2026-08-29 — Findable by assistants` with a short intro, the italic *Catalog* line (302 new implementations across 82 specs — the JavaScript backfill — no new specs; 3,704 implementations over 324 specs) and the single **Dependencies:** bullet (10 Dependabot PRs); the compare links are repointed. Version bumped in `pyproject.toml`, `uv.lock` and `app/package.json`. - **`uv.lock` repaired on the way.** The three Dependabot squash-merges #10614–#10616 (21:39–21:40 UTC yesterday) each carried the new `httpx2` / `httpx2-jsfetch` package blocks and `main` kept every copy, so `uv lock` and every `uv run` failed to parse the file — this release's version bump was the first Python-touching change to hit it. The duplicate blocks are removed and the lock re-validated (`uv lock --check` clean, 205 packages, same resolution; uv 0.10.2 also normalised a few dependency markers). Entry under Fixed in the 3.2.0 section. - First release cut under the condensed-release rule (#10810): after the merge I tag `v3.2.0` on the merge commit and publish the GitHub release from the section — condensed, never copied. ## Plan `agentic/commands/release.md` — steps 1–5 here, 6–8 after the merge. ## Test plan - [x] Completeness: every non-exempt commit in `v3.1.0..main` has its entry (18 PRs checked against the section) - [x] `uv lock --check` clean; `uv run pytest tests/unit tests/integration` — 1713 + 67 passed (incl. `test_version_sync.py`); `yarn vitest run src/global-config.test.ts` green - [x] Diff touches exactly the four release files - [ ] After merge: tag + GitHub release (condensed body), `gh release view v3.2.0`, masthead picks up the tag; watch whether `deploy-api` fires on the `pyproject.toml` change (no backend build ran for the three deps merges yesterday) --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
CHANGELOG.md); the section's own### Added / Changed / Removed / Fixedheadings in the section's order (an empty one is omitted); one bullet per NOTABLE entry — chores, dependency bumps and small fixes are left out, no fixed count — each at most two lines: bold title, one clause with the essence or the headline number, PR reference; a compare link as the last line. Numbers are copied exactly; only PR numbers from the section are cited; the full text lives only in the CHANGELOG. The v3.1.0 release page was the whole section copied — 640 lines.## Changelog + releasessection inCLAUDE.mdand.github/copilot-instructions.md(the existing PR-gate bullet moves there unchanged; the Important Rules keep a one-line pointer — the three-file sync note withagentic/commands/pull_request.mdstill holds), theCHANGELOG.mdheader states the cut procedure, andagentic/commands/release.mdstep 7 now builds the condensed body instead of copying the section. Wording is the owner's, adapted to anyplot's version files (pyproject.toml,uv.lock,app/package.json— noCITATION.cff) and to the fact that/pull_requestalready appends PR references at PR time.release.md's "exactly three files" to the four files step 4 already names.Plan
N/A — rule carried over from kurrentschrift (its
CLAUDE.md/ CHANGELOG header, 2026-08-28). The next release (v3.2.0, prepared right after this merges) is the first cut in the new shape.Test plan
CLAUDE.mdand.github/copilot-instructions.mdcarry the same three bullets; the anchor#changelog--releasesmatches GitHub's slug for the heading.